home *** CD-ROM | disk | FTP | other *** search
/ PC Media 23 / PC MEDIA CD23.iso / share / prog / anubis / mouse.txt < prev    next >
Encoding:
Text File  |  1995-10-14  |  15.9 KB  |  386 lines
  1.    Especificaciones para la librería MOUSE.H
  2.    -----------------------------------------
  3. (C) Anubis Software, todos los derechos sobre este documento están
  4. reservados. 
  5.  
  6.    Esta librería está especialmente orientada al uso del ratón. 
  7. Tiene una gran diversidad de funciones que proporcionan todo tipo
  8. de servicios, tanto para modo gráfico, como para modo texto.
  9.  
  10.    Para que funcione correctamento no se puede utilizar la opción FASTEST CODE
  11. del compilador, pues la aplicación se colgará con suma facilidad
  12. (debido al uso de interrupciones) 
  13.  
  14.  
  15. Constantes de la librería:
  16. --------------------------
  17.  
  18.    Constantes de estado:
  19.    ---------------------
  20.  
  21.    BUTTON_LEFT: Esta constante establece que el botón izquierdo está
  22. pulsado.
  23.    BUTTON_RIGHT: Esta constante establece que el botón derecho está
  24. pulsado.
  25.    BUTTON_MIDDLE: Esta constante establece que el botón central está
  26. pulsado.
  27.  
  28.    Constantes de evento:
  29.    ---------------------
  30.    Cuando se produce un evento, puede ser de diversos tipos. Y esán
  31. todos ellos definidos con las siguientes constantes.
  32.  
  33.    MOVER_RATON:               Se ha movido el ratón.
  34.    PULSAR_IZQUIERDO:          Se ha pulsado el botón izquierdo del ratón.
  35.    SOLTAR_IZQUIERDO:          Se ha soltado el botón izquierdo del ratón.
  36.    PULSAR_DERECHO:            Se ha pulsado el botón derecho del ratón.
  37.    SOLTAR_DERECHO:            Se ha soltado el botón derecho del ratón.
  38.    SHIFT_PULSADO:             Se mantiene la tecla Shift pulsada.
  39.    CTRL_PULSADO:              Se mantiene la tecla Crtl pulsada.
  40.    ALT_PULSADO:               Se mantiene la tecla Alt pulsada.
  41.    PULSAR_CENTRO:             Se ha pulsado el botón central.
  42.    SOLTAR_CENTRO:             Se ha sotado el botón central.
  43.  
  44. // Existen eventos especiales que son detectados mediante software:
  45.    DOBLE_CLICK_DERECHO:       Doble pulsación del botón derecho
  46.    DOBLE_CLICK_IZQUIERDO:     Doble pulsación del botón izquierdo.
  47.  
  48. Existen algunos tipos predefinidos del ratón:
  49. typedef struct  {
  50.    WORD despx; Indica el desplazamiento del pixel de valor respecto
  51.    a la esquina superior izquierda. debe tener un valor entre 0 y 16
  52.    WORD despy; Igual que despx, pero respecto al eje y.
  53.    WORD buffer[32]; Contiene dos dibujos del ratón. La primera zono de
  54.    16 WORD's debe tener la máscara con AND del dibujo y la segunda
  55.    zona debe tener una máscara con XOR del dibujo.
  56. } PUNT_RATON;
  57.  
  58.    La estructuera PUNT_RATON se utiliza para definir tipos de cursores
  59. del ratón en modo gráfico.
  60.  
  61. typedef struct {
  62.    int posx; Es la posición horizontal del ratón en pixels.
  63.    int posy; Es la posición vertical del ratón en pixels.
  64.    int estado; Es un bit que indica el estado del ratón; Puede tomar
  65.    los valores BUTTON_LEFT, BUTTON_RIGHT y BUTTON_MIDDLE en una máscara.
  66. } MOUSE_INFO;
  67.  
  68.    La estructura MOUSE_INFO se utiliza para centralizar todas las variables
  69. del ratón.
  70.  
  71.  
  72.    Declaración de las variables globales de la librería:
  73.  
  74. void far *mouseoldroutine;
  75. --------------------------
  76.    Esta variable no debe ser nunca modificada por el usuario directamente
  77. contine el valor de la rutina anterior para controlar el ratón antes
  78. de utilizar las funciones InitMouse o similares.
  79.    Para el usuario de la librería esta rutina no existe.
  80.  
  81. volatile WORD mousex;
  82. ---------------------
  83.    Esta variable, siempre que se haya inicializado correctamente el
  84. ratón, contiene la posición horizontal del puntero de ratón en
  85. pixels.
  86.    La inicialización del ratón se debe hacer con InitMouse.
  87.  
  88. volatile WORD mousey;
  89. ---------------------
  90.    Esta variable, siempre que se haya inicializado correctamente el
  91. ratón contiene la posición vertical del puntero de ratón en
  92. pixels.
  93.  
  94. volatile WORD estado;
  95. ---------------------
  96.    Esta variable contiene, siempre que se haya inicializado correctamente
  97. el ratón el estado de los botones del ratón. Puede contener los 
  98. valores BUTTON_LEFT, BUTTON_RIGHT o BUTTON_MIDDLE en una máscara.
  99. Indicando cada un de dichos valores que el botón correspondiente está
  100. siendo pulsado en esos momentos. 
  101.    Un ejemplo de uso de esta forma sería el siguiente:
  102.    while (estado & BUTTON_LEFT) {
  103.       puts("El botón izquierdo del ratón está pulsado");
  104.    }// end while
  105. o el siguiente
  106.    while (estado == BUTTON_LEFT)  {
  107.       puts("El botón izquierdo del ratón está pulsado");
  108.    }// end while
  109. NOTA: Esta variable, aunque existe, no se suele utilizar, pués directamente
  110. se usa mouse_evento.
  111.  
  112. volatile WORD mouse_evento;
  113. ---------------------------
  114.    Esta variable, según como se haya inicializado el ratón contiene
  115. el último evento que se ha producido en el ratón. Estos pueden
  116. ser todos los descritos en las constantes de evento.
  117.  
  118. void far (*EventMouseRoutines[10]) (void);
  119. ------------------------------------------
  120.    Esta variable es un array para utilizar el ratón con el sistema
  121. de gestion de eventos. No es aconsejable, ni útil el que sea 
  122. manipulada directamente.
  123. NOTA: Olvidese que existe esta declaración.
  124.  
  125. char EventMouseIndiceRutinas;
  126. -----------------------------
  127.    Esta variable es un apuntador sobre la variable anterior y tampoco
  128. debe manipularse directamente.
  129.  
  130. char EventMouseIndiceAuxiliar;
  131. ------------------------------
  132.    Igual que la anterior.
  133.  
  134. int double_click_delay;
  135. -----------------------
  136.    Establece el tiempo para detectar pulsaciones dobles.
  137.  
  138.  
  139. void far (*EventMouseFastRoutines[10])(void);
  140. ---------------------------------------------
  141.    Existen dos colas de ejecución para eventos del ratón; una se dedica a
  142. la gestión de eventos de carga pesada, y la otra se dedica a la gestión de
  143. los eventos con carga ligera; Esto significa que los eventos de esta pila
  144. se ejecutan siempre, incluso cuando se esta en el interior de algún algoritmo
  145. que se ha cerrado en torno a la gestión de eventos.
  146.    Es similar a EventIddleExecutión, salvo que sucede con el ratón y no como
  147. norma general.
  148.  
  149. char EventMouseIndiceFastRutinas;
  150. ---------------------------------
  151.    Es una variable auxiliar para EventMouseFastRoutines.
  152.  
  153. char EventMouseIndiceFastAuxiliar;
  154. ----------------------------------
  155.    Es una variable auxiliar para EventMouseFastRoutines.
  156.  
  157. char EventMouseFastSkip;
  158. ------------------------
  159.    Es una variable auxiliar para EventMouseFastRoutines.
  160.  
  161. boolean nevent
  162. --------------
  163.    Esta variable, también es una variable auxilair para EventMouseFasRoutines
  164. y lo que indica es que el evento de ratón que acontece es nuevo. Se utiliza
  165. porque La ejecución rápida de rutinas no puede bajo ningún concepto variar
  166. el valor de mouse_evento, ya que después es utilizado por EventMouseRoutines.
  167.  
  168.  
  169.    Funciones proporcionadas por la librería:
  170.    -----------------------------------------
  171. void ConvertMouse(void)
  172. -----------------------
  173.    Esta función convierte los eventos simples de ratón en eventos completos
  174. de ratón. Asi, cuando se ha llamado a esta función, la variable mouse_event
  175. puede contener dos nuevos eventos;
  176.    DOBLE_CLICK_DERECHO y DOBLE_CLICK_IZQUIERDO son los eventos que se han
  177. añadido a los eventos producidos por hardware.
  178.    Esta función consume como recursos el tiempo especificado en double_click_delay
  179. ya que utiliza un espacio de tiempo para comprobar si se ha producido una
  180. doble pulsación y eliminar la pulsación simple para provocar una pulsación
  181. doble. (Es sencillo, pero debe consumir tiempo).
  182.    La función utiliza la función delay() de la librería dos.h
  183.  
  184. void EventMouseFastExecution(void);
  185. -----------------------------------
  186.    Esta llamada provoca que se ejecuten todos los eventos del ratón que
  187. se han solicitado. Es práctica y util ya que centraliza los eventos del ratón
  188. y no se debe estar haciendo polling siempre. Los eventos que ejecuta esta
  189. rutina son los rápidos. "Es decir" los que se ejecutarán siempre aun cuando
  190. se este en un procedimiento que ha absorbido las funciones. Esto significa
  191. que siempre que se produce un evento de ratón, pasará por esta función.
  192.    Es importante destacar que las funciones que reciben este evento no deben
  193. bajo ninguna circunstancia modificar el valor de mouse_event, ya que el
  194. evento deberá pasar después a las funciones normales (no fast).
  195.    Antes de nada, esta función llama a la función ConvertMouse porque los
  196. eventos que se tratan son completos, los producidos por software también.
  197.    Por todo lo demás, el funcionamiento es analogo el que hace la ejecución
  198. de eventos de ratón normal.
  199.  
  200. void EventMouseExecution(void);
  201. -------------------------------
  202.    Provoca la ejecución de todas las funciones almacenadas en la
  203. pila de ejecución de la pila de eventos del ratón. Dichas funciones
  204. contienen tratamientos del ratón. Y deben meterse en la pila mediante
  205. la función EventEmpilaMouseRutina(...)
  206.    Sólo se ejecutan dichas funciones cuando se ha producido un evento
  207. de ratón. Lo cual proporciona una eficiencia mayor y una centralización
  208. de todo el sistema. Haciendo que el OverHead sea menor que el dado
  209. al hacer un poling sobre el ratón en todas las funciones que lo 
  210. desean utilizar.
  211.    Esta función llama automaticamente a EventMouseFastExecutión. Lo cual
  212. significa que se procesan todos los eventos producidos. Rápidos y no rápidos.
  213.    Los eventos tratados son todos, tanto hardware como software.
  214.  
  215. void EventMouseFinFastExecution(void);
  216. void EventMouseFinExecution(void);
  217. ----------------------------------
  218.    Provoca el fin de ejecución de las funciones del ratón sin ejecutar
  219. las posteriores a la que se ha ejecutado. Esta función sólo debe ser
  220. utilizada por las funciones que estén dentro de la pila de ejecución.
  221. Su manejo es eficaz y proporciona una forma adecuada de controlar
  222. el flujo de ejecución de las rutinas del ratón. Además permite
  223. jerarquias en las funciones de eventos del ratón.
  224.  
  225. void MouseSkipFastExecution(void);
  226. void MouseSkipExecution(void);
  227. ------------------------------
  228.    Provoca el fin de ejecución de las funciones del ratón, pero no
  229. elimina el último evento del ratón que ha provocado la ejecución. Con
  230. lo cual se volverá a ejecutar toda la pila de funciones de nuevo.
  231.  
  232. void EventEmpilaMouseFastRutina( void far (*) (void));
  233. void EventEmpilaMouseRutina( void far (*) (void));
  234. --------------------------------------------------
  235.    Esta función empila una rutina de ejecución de eventos de ratón
  236. en la pila de eventos del ratón. Dicha función se ejecutará siempre 
  237. que se produzca un evento del ratón.
  238.  
  239. void EventDesempilaMouseFastRutina();
  240. void EventDesempilaMouseRutina();
  241. ---------------------------------
  242.    Esta función desempila la última función que se ha metido en la
  243. pila de ejecución. Normalmente no se utiliza. 
  244.  
  245.  
  246. void interrupt MouseEvent();
  247. ----------------------------
  248.    Esta rutina es el gestor de interrupciones que se coloca como
  249. manipulador de la librería. Se coloca en su sitio cuando se llama
  250. a la funcion InitMouse();
  251.    Es esta función la que se encarga de que las variables mouse_evento,
  252. mousex, mousey y estado tengan lo que les corresponde tener.
  253. NOTA: Esta rutina no debe utilizarse nunca, es decir que para el
  254. usuario no existe.
  255.  
  256. void InitMouse(int);
  257. --------------------
  258.    Esta función inicializa el ratón. Para poder funcionar con las
  259. variables mousex, mousey, etc.
  260.    La función sólo debe llamarse una vez en todo el programa, a no
  261. ser que se la finalice con la funcion MouseOff.
  262.    El parámetro que se le pasa es un valor indicando los eventos que
  263. deben considerarse como eventos. (Vease Extensiones del MS-DOS para
  264. una completa definición de las máscaras). Normalmente los valores 
  265. más utilizados son 0x7E y 0x7F.(Que implican todos los eventos del ratón).
  266.  
  267. void MouseOFF(void);
  268. --------------------
  269.    Desactiva la instalación del raton con InitMouse();
  270.  
  271. void show_mouse(void);
  272. ----------------------
  273.    Hace que el puntero del ratón sea visible.
  274.  
  275. void ide_mouse(void);
  276. ---------------------
  277.    Hace que el puntero del ratón sea invisible.
  278.  
  279. void pos_mouse(x, y);
  280. ---------------------
  281.    int x;
  282.    int y;
  283.  
  284.    Establece la posición del ratón a las coordenadas (x,y). Estas
  285. coordenadas están en pixels incluso en los modos de texto donde hay
  286. que aplicar un factor de conversión multiplicando por 8 dichos valores.
  287.  
  288. void tasa_int_mouse(int);
  289. -------------------------
  290.    int int;
  291.  
  292.    Establece el númer de veces que se testea el ratón para producir
  293. la interrupción adecuada. No es necesario usarla.
  294.  
  295. void pagina_mouse( pag);
  296. ------------------------
  297.    int pag;
  298.  
  299.    Establece la página de visualización del ratón. Por defecto es la
  300. página 0 y no suele ser necesario cambiarla, a no ser que se utilice
  301. otra página de visualización para la pantalla. Cosa muy poco frecuente.
  302.  
  303. struct mouse inf_mouse(void);
  304. -----------------------------
  305.    Devuelve una estructura del tipo INF_RATON rellena de los datos
  306. actuales del ratón. No se usa si se emplean las variables de estado
  307.  
  308. int boton_mouse(void);
  309. ----------------------
  310.    Devuelve una variable con el estado de los botones del ratón. Tampoco
  311. se usa.
  312.  
  313.  
  314. struct mouse inf_suelta_mouse(int ,int *, int  *,int  *);
  315. ---------------------------------------------------------
  316. En realidad no se utiliza con el sistema de las variables.
  317.  
  318. struct mouse inf_pulsa_mouse(int ,int *, int *,int *);
  319. ------------------------------------------------------
  320. En realidad no se utiliza con el sistema de las variables.
  321.  
  322. void init_mouse(void);
  323. ----------------------
  324. Es otra forma de inicializar el ratón, de hecho, sirve para inicializar
  325. el ratón y no utilizar las variables mousex,mousey,...
  326. Está bastante obsoleta ya que es una forma retrasada de controlar el ratón.
  327.  
  328. void init_double_click (void);
  329. ------------------------------
  330.  
  331. int test_double_click(void);
  332. ----------------------------
  333.  
  334. void limit_horizontal_area_raton(int ,int );
  335. --------------------------------------------
  336. Limita las areas del ratón.
  337.  
  338. void seleccionar_puntero_texto(int ,int ,int );
  339. -----------------------------------------------
  340.  
  341. void cambiar_puntero_grafico(PUNT_RATON );
  342. ------------------------------------------
  343.  
  344. PUNT_RATON leer_puntero_raton(char *);
  345. --------------------------------------
  346.  
  347. void grabar_puntero_raton (char *, PUNT_RATON );
  348. ------------------------------------------------
  349.  
  350.  
  351.  
  352.  
  353. NOTAS PARA LAS FUNCIONES DE EJECUCION DE VENTOS:
  354. ------------------------------------------------
  355.  
  356.    -El uso del ratón por parte de todas las funciones es bastante 
  357. generalizado. Si se produce un evento, entonces todas las funciones
  358. comprueban si el evento les pertenece, o es el evento que las dispara
  359. y en dicho caso ejecutan el código que les pertoca.
  360.  
  361.    -Ciertas funciones necesitan retener el uso del ratón por un
  362. tiempo determinado. Por ejemplo el caso de funciones que se ejecutan
  363. mientras un boton del ratón está pulsado. Estas funciones son factibles
  364. siempre y cuando se apropien del ratón, o finalicen la ejecución del
  365. mismo cuando han terminado con el. Ya que si no producen un estado
  366. fantasma que no ha activado a los demás eventos  y puede conllevar a
  367. la ejecución de rutinas no activadas correctamente.
  368.  
  369.    -A veces nos interesará anular la ejecución de las demás funciones
  370. sin que se termine la ejecución de las mismas. Es decir, apropiarnos
  371. del evento del ratón que ha sucedido, pero sin castrar la ejecución de
  372. las demás funciones. Esto se consigue de una forma muy sencilla.
  373. Basta con asignar a la variable mouse_evento un cero y nos aseguramos
  374. que las demás funciones no tomen el evento del ratón como suyo. Ya 
  375. que todas deben comprobar que tipo de evento se ha producido y
  376. no detectarán evento alguno. Así la ejecución proseguirá hasta el
  377. final sin provocar que dos funciones se apropien del mismo evento.
  378. También se puede conseguir con la funcion EventMouseFinExecution.
  379.  
  380.    -Se ha observado que existen dos colas de ejecución para eventos del
  381. ratón. Esto es debido a que en las aplicaciones que utilizen el sistema
  382. AVISION pueden querer que ciertas rutinas no se interrumpan cuando un 
  383. determinado procedimiento se ha apropiado del ratón. Esto implica que
  384. ese procedimiento ejecute EventMouseFastExecution y que no se ejecute
  385. EventMouseExecution. (Para mayor información leanse documentos sobre
  386. el sistema AVISION (Anubis Vision) )